Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…s for tool calling.

… into PromptTarget.send_prompt_async

C4 lands the in-tree wiring for the generic tool-use loop introduced by C2/C3:

- TargetCapabilities gains supports_tool_use: bool (default False) and
  CapabilityName.TOOL_USE for the corresponding enum value, matching the
  existing supports_X / "supports_X" naming convention used by every
  other capability.
- TargetConfiguration grows tool_event_policy + tool_backend kwargs,
  both gettable/settable properties. The setter (and constructor)
  validate that a non-None tool_backend requires supports_tool_use=True;
  otherwise they raise ValueError immediately. ToolBackend /
  ToolEventPolicy imports are quoted + behind TYPE_CHECKING to keep
  pyrit.prompt_target.common from importing pyrit.tools eagerly.
- PromptTarget.send_prompt_async picks up @tool_loop (below the existing
  @Final). The wrapper is a no-op when tool_event_policy is None, so
  every existing target keeps its current behavior. _tool_parser
  (property, default None) and _tool_schemas() (default []) are added
  on the base class as the two collaborators @tool_loop reads.
- _permissive_configuration is updated to flip supports_tool_use=True
  alongside the other supports_X flags so the all-flags-on probe loop
  in test_discover_target_capabilities still sees every CapabilityName
  value as supported.

tests/unit/tools/conftest.py drops the hand-decorated @tool_loop on
_FakeToolTarget.send_prompt_async (which would now violate the base
class's @Final) and instead wires policy + backend through
TargetConfiguration. _tool_parser becomes a subclass property since
the base class now defines one.

Tests:
- test_tool_event_policy.py adds U7 (capability flag wiring through the
  wrapper) plus dataclass field defaults and the TargetConfiguration
  validator.
- test_prompt_target_tool_loop.py adds U1 / U2 (DB-end) / U8 / U9 / U11
  exercised against a _ProductionShapedTarget that uses the real
  base-class _get_normalized_conversation_async (memory round-trip via
  patch_central_database). Plus default-_tool_parser / -_tool_schemas
  assertions.

Validation: 8104 unit tests pass; pre-commit clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…nd Response target

This commit is intentionally empty. It records a scope decision made in
response to PR review feedback. No code changes - the C5 working set was
uncommitted and has been reverted.

# Why we're dropping C5

Review feedback raised two concerns the original C5 did not address:

  1. **Duplication against OpenAIResponseTarget.** The Response target
     already implements an agentic tool loop (openai_response_target.py
     lines 590-626), the canonical function_call envelope (lines 666-674),
     a Python-callable dispatch registry (custom_functions), and an
     allow-list-ish hook (fail_on_missing_function). C5 layered a parallel
     implementation on top for the Chat target instead of converging both
     targets onto one stack.
  2. **Chat Completions is on its way out.** OpenAI has publicly framed
     the Responses API as the long-term replacement for Chat Completions.
     Investing in tool-call plumbing for a deprecated endpoint ages out
     fast and obscures the actual value of this PR.

The right framing is: this PR is not "tool calling for all targets." It
is "pluggable tool-execution backends + a client-side agentic loop for
non-Responses-API targets." The Responses API is one transport; this PR
is the in-process abstraction that works for every transport.

# What survives unchanged

C1 (mcp SDK dep), C2 (tools/ scaffold + LocalToolBackend), C3 (MCPClient
+ MCPToolBackend + Docker stub), and C4 (capability flag + @tool_loop
wired on the base class) all remain shipped. The genuinely-novel work -
local stdio MCP, pluggable backend ABC, ToolEventPolicy (RAISE /
EXECUTE / RETURN_RAW), allowed_tools - is unaffected.

# The new design

**One agentic loop driver.** The @tool_loop decorator on
PromptTarget.send_prompt_async (shipped in C4) is the only loop driver.
Every target's _send_prompt_to_target_async returns exactly ONE Message
per call. The decorator stitches iterations into the response list.

**One tool execution layer.** Every dispatched call flows through
ToolBackend.dispatch_async(call) -> envelope. Backends (LocalToolBackend
for Python callables, MCPToolBackend for stdio MCP subprocesses, future
DockerMCPToolBackend, future CompositeToolBackend) are interchangeable
behind a single ABC.

**Migrate OpenAIResponseTarget onto the decorator (new C5).** Delete
the in-class while loop (lines 590-626). _send_prompt_to_target_async
becomes "build body, call API, parse response into one Message, return."
Add _tool_parser returning CanonicalEnvelopeParser (extracts only
function_call pieces; reasoning, mcp_call, web_search_call, etc.
continue to pass through to Memory without dispatch). Translate the
configured backend's schemas into the Responses-API tools shape inside
_construct_request_body (without clobbering an existing
extra_body_parameters["tools"]). Wrap custom_functions as a
LocalToolBackend internally with DeprecationWarning(removed_in="0.16.0"),
preserving the existing fail_on_missing_function semantics.

**Integration tests (new C6).** Rewrite to use the Response target as
the sole OpenAI tool-calling path, plus end-to-end scenario tests
against the real echo_mcp_server.

**OpenAIChatTarget receives no tool-calling support in this PR.** A
future PR can pull Chat onto the same abstractions if anyone still
wants it, but the recommended OpenAI tool-calling path becomes the
Responses API.

# Risks

  * Behavior-parity on the Response target: callers that rely on
    `len(send_prompt_async(...)) == iterations` rather than scanning
    piece types will need updating. Existing function-chaining tests act
    as sentinels.
  * `custom_functions` deprecation must preserve `fail_on_missing_function`
    semantics through the LocalToolBackend wrapper.
  * Response parser must continue to round-trip non-`function_call` piece
    types (reasoning, mcp_call, etc.) to Memory without dispatching.
  * `extra_body_parameters["tools"]` takes precedence over backend-derived
    tools so existing manual configs keep working.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

C6 collapses the Response target in-class agentic loop into the @tool_loop
decorator shipped in C4, and routes tool dispatch through LocalToolBackend
(wrapping the existing custom_functions registry as a deprecation shim).

# What changed

- _send_prompt_to_target_async no longer runs a while loop. It now returns
  exactly one Message per call. The agentic loop is driven by @tool_loop on
  the base class.
- Added _tool_parser returning CanonicalEnvelopeParser from
  pyrit/tools/parsers.py. The parser extracts only function_call pieces;
  reasoning, mcp_call, web_search_call, computer_call, local_shell_call, etc.
  pass through to Memory unchanged because the parser ignores them and the
  decorator exits cleanly on the empty parse.
- Added _tool_schemas() translating the configured backend schemas into the
  Responses-API tools shape.
- _construct_request_body injects tools=... when the backend has schemas.
  User-supplied extra_body_parameters["tools"] takes precedence.
- supports_tool_use=True on _DEFAULT_CONFIGURATION.
- custom_functions= now emits DeprecationWarning(removed_in="0.16.0").
  Internally wraps into a LocalToolBackend. A LocalToolBackend is always
  installed (populated or empty) so legacy target._custom_functions[name]=fn
  mutations keep affecting dispatch via a back-compat property.
- Constructor deep-copies the class-level _DEFAULT_CONFIGURATION before
  mutating it (PromptTarget.get_default_configuration returns the singleton,
  so otherwise one instances tool_backend would leak across every other
  instance).

# What did NOT change

The legacy _find_last_pending_tool_call, _execute_call_section, and
_make_tool_piece helpers remain in place. They are no longer called from
production code, but existing tests still cover them; cleanup is deferred to
the same follow-up PR that removes the custom_functions kwarg after the
0.16.0 deprecation window.

# Tests

- New tests/unit/prompt_target/target/test_openai_response_target_c6_migration.py
  with 7 tests covering deprecation warning, dispatch through user-supplied
  LocalToolBackend, schema injection, extra_body precedence, no-backend
  behavior, and reasoning-only passthrough.
- All 5 existing function-chaining sentinel tests in
  test_openai_response_target_function_chaining.py pass unchanged: the
  back-compat _custom_functions property keeps in-place mutations working.

8131 unit tests green; pre-commit clean (ruff format, ruff check, ty).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

C7 adds end-to-end integration coverage of the @tool_loop decorator,
MCPToolBackend, and MCPClient stack against the real echo_mcp_server
subprocess. Only the OpenAI Responses HTTP layer is mocked; the MCP
stdio subprocess, AsyncExitStack lifecycle, canonical envelope
round-trip, and RedTeamingAttack execution path all run unmocked.

# What ships

tests/integration/tools/test_red_teaming_with_tools.py with three tests:

1. test_red_teaming_response_target_with_mcp_echo - end-to-end smoke
   test. RedTeamingAttack drives OpenAIResponseTarget configured with a
   MCPToolBackend pointing at echo_mcp_server. The Responses API mock
   returns one function_call followed by a stop response. Asserts the
   tool call actually reaches the MCP subprocess and the result lands
   back in the second API call as a function_call_output.

2. test_red_teaming_persists_canonical_transcript_in_memory - verifies
   the canonical envelope contract (plan section 13). Reads the
   conversation back from Memory after attack.execute_async returns
   and asserts the function_call and function_call_output pieces are
   present, in order, with matching call_ids.

3. test_red_teaming_dispatches_all_tool_calls_per_turn - regression
   test for the intentional behavior change from C6. The pre-C6 in-class
   loop in OpenAIResponseTarget only dispatched the LAST function_call
   per turn; the @tool_loop decorator now dispatches every call in
   declaration order. Issues both echo and add in one response and
   asserts both results land in the next API call.

# Test infrastructure

- LocalMCPServerSpec uses command=sys.executable + args=(echo_server,).
- Mock objective scorer returns a true score so RedTeamingAttack exits
  cleanly after one turn.
- Mock adversarial target returns a single scripted prompt wrapped as
  list[Message] (PromptTarget.send_prompt_async contract).
- Score, ComponentIdentifier, and PromptTarget MagicMock(spec=...) usage
  matches the existing tests/unit/executor/attack patterns.

All three integration tests pass; pre-commit clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Adds a parser that walks text MessagePieces for marker-delimited

JSON blocks of the form {"name": ..., "arguments": {...}} and emits

canonical ToolCall instances. Marker pattern, call_id prefix, and

surrounding-text policy (truncate / extract-all / strict) are all

constructor-controlled so a single class covers angle-bracket,

pipe-delimited tag pair, and other chat-template syntaxes.

The parser is the F1 (per plan) piece that lets non-Responses-API

targets participate in PyRIT's @tool_loop without a per-vendor

parser implementation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

TargetConfiguration.as_identifier_params() now snapshots the configured

tool_event_policy (behavior + max_tool_iterations) and tool_backend

(backend class + sorted list of advertised tool names). Two targets

that differ only in their tool backend now get distinct identifiers,

which downstream consumers rely on to route by target identity.

Schema serialization is best-effort: backends with shape-quirky schemas

that lack a recoverable 'name' field are silently dropped from the

identifier surface. Exact callables and transports are not serialized

because they are not deterministic.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

PyRIT's docs build uses MyST, not reStructuredText, so reST roles like

:class:\Foo\ render as literal text in the rendered docs and mismatch

the rest of the codebase. Convert all roles in the new pyrit/tools/

module to plain double-backtick code spans, and drop the in-flight

commit-numbering references (C1/C2/...) that were carry-overs from the

shipping plan and no longer mean anything in source.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…aises

Three small cleanups in the new tools test suite:

1. Remove @pytest.mark.asyncio decorators -- the project sets

   asyncio_mode='auto' in pyproject.toml so the marker is a no-op that

   creates the appearance of opt-in async test discovery.

2. Narrow pytest.raises((AttributeError, Exception)) to

   dataclasses.FrozenInstanceError on the two frozen-dataclass guards

   in test_mcp_client.py. The previous pattern matched every Exception

   and would have masked unrelated regressions.

3. Drop in-flight C1/C2/.../C10 commit-id strings from test docstrings;

   they referenced the shipping plan, not the source tree, and read as

   noise after the commits land.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The base default for _tool_schemas() now reads self.configuration.tool_backend.schemas verbatim. Subclasses that need wire-format wrapping (currently only OpenAIResponseTarget, which prepends type=function) override the method and reuse the base via super() to get the raw schemas.

Removes a small but real duplication risk for the upcoming AzureMLChatTarget / HuggingFaceChatTarget tool-calling paths, which would otherwise each reimplement the 'read schemas from configured backend' boilerplate.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

AzureMLChatTarget now participates in PyRIT's @tool_loop when callers
supply a ToolCallParser at construction. The parser flips
supports_tool_use=True on the default capabilities so callers don't
need to construct a custom_configuration just to opt in. A convenience
tool_backend kwarg installs the backend onto the configuration in one
step.

Wire format: _tool_schemas() wraps the backend's schemas in the OpenAI
Chat Completions tools shape (with each schema nested under a
"function" key). _construct_http_body_async injects the wrapped
schemas as a top-level tools field when non-empty. Deployments unwrap
that envelope before passing to tokenizer.apply_chat_template; see
plan section 12.9 for the contract.

Response handling: _complete_chat_async now returns the parsed JSON
body (was: string output). The new _materialize_response walks the
response dict and emits one text MessagePiece for the output field
plus one function_call MessagePiece per envelope in the tool_calls
field; CanonicalEnvelopeParser then finds those pieces in the loop's
next iteration.

The no-tools path is unchanged: requests without tool_parser produce
byte-identical request bodies, verified by
test_request_body_omits_tools_key_when_no_backend.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Same shape as the AzureMLChatTarget F2 change: callers supply a
ToolCallParser at construction; the parser flips
supports_tool_use=True on the default capabilities so no
custom_configuration is required to opt in. A convenience tool_backend
kwarg installs the backend onto the configuration in one step.

Wire format differs from AzureML because HuggingFace runs the model
in-process via the transformers library:

  * _tool_schemas() returns the bare backend schemas (no OpenAI
    envelope) because tokenizer.apply_chat_template expects bare
    function schemas, not the Chat Completions wrapper.
  * _apply_chat_template forwards tools= into apply_chat_template
    when schemas are present; the model's tool-trained chat template
    renders the model-family-specific tools block (Qwen wraps in
    <tools>...</tools>, Llama uses a system-message preamble, etc.).
  * _build_chat_messages now walks every piece in each message and
    converts function_call / function_call_output envelopes to the
    chat-template tool message shape (assistant + tool_calls list,
    role=tool + tool_call_id) so the model sees the canonical
    in-context tool conversation.

The no-tools path is unchanged: without tool_parser, no tools key is
passed to apply_chat_template and no tool message translation runs.

The user-supplied tool_parser walks the response text for inline
tool-call markers; InlineToolCallParser is the typical choice for
ChatML-style angle-bracket markers, but the user can supply any
ToolCallParser implementation (different marker regex, different
mode).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Adds tests/integration/tools/test_azure_ml_with_tools_integration.py
exercising the full PyRIT @tool_loop stack against AzureMLChatTarget
with only the HTTP layer mocked. The mocked responses match the §12.9.2
canonical envelope shape: first response carries a tool_calls field
that the loop dispatches via LocalToolBackend; second response is the
final assistant text.

Asserts the canonical four-piece transcript shape persists in Memory:
[user text, assistant function_call, tool function_call_output,
assistant text], with the call_id round-tripping between the
assistant function_call piece and the tool function_call_output piece,
and the tool output reflecting the actual dispatched callable's return
value.

Also covers the no-tools backward-compatibility path: a target
constructed without tool_parser produces a request body that has no
tools key, proving the F2 changes do not regress existing AzureML
deployments that don't carry the patched scoring script.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>